Trading configuration > Fields for adding application pickups and application deliveries > Web Services API pickup and delivery configuration

Web Services API pickup and delivery configuration

The Web Services API transport can be used for application exchanges only.

Application pickup

When a community uses the Web Services API to retrieve messages from a back-end system, the Web Services API transport uses a global embedded Web Services API server. The application posts messages to a URL in the following format:

http://host:5080/services/MessageService

Where:

host is the fully qualified domain name or IP address of the computer running Activator.
The default port is 5080. You can modify this value.

To set up this transport for a community, you add a Web Services API server application pickup. No other configuration is required.

To modify the global API HTTP embedded server, select System management > Manage embedded servers. Because the global server is shared by all communities, any configuration changes affect all communities.

The Web Services API application pickup can accept a maximum file size of about 15 megabytes. This is because of the way the Apache web server, which is embedded within Activator, requires files to be written into memory. This behavior can quickly exhaust the heap memory available to the Java virtual machine within Activator.

The work-around to the file-size limitation is for the back-end Web Services client to send a URL of the file’s location, rather than the file itself, to Activator. The URL the client sends specifies where Activator can pick up the outbound file for packaging and sending.

After Activator consumes the file, it places the file into a virtual data object. As the payload is not stored in memory, it does not consume any of the JVM memory.

For a Web Services application pickup to accept a URL instead of the actual file, you do not have to change the configuration within Activator. However, you must have a programmer make a change within the Web Services client that submits outbound files to Activator.

Application delivery

When a community uses the Web Services API to send messages received from partners to a back-end system, the Web Services API transport uses an API client to send messages to a back-end web server. This setup requires the help of a technician or developer who is familiar with Web Services and the Web Services Description Language (WSDL). The technician or developer needs to provide a server implementation of the provided MessageService WSDL.

There are two ways to get the WSDL document that describes the requirements for both the server and client:

The first way is to set up a Web Services API server application pickup and then point a browser to the following URL:

http://host:5080/services/MessageService?wsdl
Where host is the fully qualified domain name or IP address of the computer running Activator. Use localhost if the browser and Activator are on the same computer.
If you have the optional Software Development Kit, the second way is to get the following file in the SDK directory tree:
sdk\wsdl\TradingEngineNodeServices\MessageService.wsdl
Sample client implementations are also available in the SDK directory tree. For more information see the SDK Developer’s Guide.

When the back-end web server has been configured according to the WSDL requirements, you can enter the URL for posting messages to the back-end server in the configuration field for the Web Services API client in the delivery wizard.

Click Next if you want to name the exchange. Otherwise, click Finish.

After the transport has been set up, you have the option of sending the message payload (the default) or only the URL that points to the payload. If you choose to send only the URL, the back-end system uses the URL to retrieve the payload from Activator backup directory. To enable this option:

Click Application delivery in the navigation graphic at the top of the community Summary page.
In the list of deliveries, click the Web Services API client exchange.
Click the Advanced tab.
Select Send the payload URL only.
Click Save changes.

Because the payload is retrieved from the backup directory, there are two conditions that must be met if you choose to send the payload URL only:

Backing up files must be enabled for the WebServices API client application delivery.
If you have set up a schedule on Activator for deleting messages, the back-end must retrieve the payload before the next scheduled purge occurs or the payload is lost.